Get rid of GDK_PIXBUF_ERROR_HEADER/PIXEL_CORRUPT and use CORRUPT_IMAGE.

Wed Oct 10 11:52:17 2001  Owen Taylor  <otaylor@redhat.com>

	* gdk-pixdata.c gdk-pixbuf.h: Get rid of
	GDK_PIXBUF_ERROR_HEADER/PIXEL_CORRUPT and use CORRUPT_IMAGE.
	Get rid fo GD_PIXBUF_ERROR_UNKNOWN_FORMAT and use the
	existing UKNOWN_TYPE error. (#58308)

	* gdk-pixbuf.h, gdk-pixdata.c: Rename gdk_pixbuf_new_from_stream()
	back to gdk_pixbuf_new_from_inline(). Rework docs to try
	and be helpful for the common case. (#58308)

diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog
index 5f40de330042326ea06081d64c8a34f83bcd1320..e2c37c7e7c98ef5961d3aa5b36f2dd45b6513ad0 100644 (file)
--- a/gdk-pixbuf/ChangeLog
+++ b/gdk-pixbuf/ChangeLog
@@ -1,3 +1,14 @@
+Wed Oct 10 11:52:17 2001  Owen Taylor  <otaylor@redhat.com>
+
+       * gdk-pixdata.c gdk-pixbuf.h: Get rid of 
+       GDK_PIXBUF_ERROR_HEADER/PIXEL_CORRUPT and use CORRUPT_IMAGE.
+       Get rid fo GD_PIXBUF_ERROR_UNKNOWN_FORMAT and use the
+       existing UKNOWN_TYPE error. (#58308)
+
+       * gdk-pixbuf.h, gdk-pixdata.c: Rename gdk_pixbuf_new_from_stream()
+       back to gdk_pixbuf_new_from_inline(). Rework docs to try
+       and be helpful for the common case. (#58308)
+
 2001-10-05  Sven Neumann  <sven@gimp.org>
 
        * gdk-pixbuf/gdk-pixbuf-io.c

diff --git a/gdk-pixbuf/gdk-pixbuf.h b/gdk-pixbuf/gdk-pixbuf.h
index d0263bdc2d0ddb36951416258475cb0a313b9b96..f63ce7731cf43951769be3dc82fe96c98653a5be 100644 (file)
--- a/gdk-pixbuf/gdk-pixbuf.h
+++ b/gdk-pixbuf/gdk-pixbuf.h
@@ -75,12 +75,6 @@ typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
 #define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark ()
 
 typedef enum {
-        /* stream header corrupt */
-       GDK_PIXBUF_ERROR_HEADER_CORRUPT,
-        /* stream pixel data corrupt */
-       GDK_PIXBUF_ERROR_PIXEL_CORRUPT,
-        /* stream header corrupt */
-       GDK_PIXBUF_ERROR_UNKNOWN_FORMAT,
         /* image data hosed */
         GDK_PIXBUF_ERROR_CORRUPT_IMAGE,
         /* no mem to load image */
@@ -148,8 +142,8 @@ GdkPixbuf *gdk_pixbuf_new_from_data (const guchar *data,
                                     gpointer destroy_fn_data);
 
 GdkPixbuf *gdk_pixbuf_new_from_xpm_data (const char **data);
-GdkPixbuf* gdk_pixbuf_new_from_stream  (gint          stream_length,
-                                        const guint8 *stream,
+GdkPixbuf* gdk_pixbuf_new_from_inline  (gint          data_length,
+                                        const guint8 *data,
                                         gboolean      copy_pixels,
                                         GError      **error);
        

diff --git a/gdk-pixbuf/gdk-pixdata.c b/gdk-pixbuf/gdk-pixdata.c
index 8437b46065fa84e115c5270ceb33081a84ad63cf..b9e4c70bb6e2298d0bcae934e9ee10be405db458 100644 (file)
--- a/gdk-pixbuf/gdk-pixdata.c
+++ b/gdk-pixbuf/gdk-pixdata.c
@@ -143,17 +143,17 @@ gdk_pixdata_serialize (const GdkPixdata *pixdata,
 
 #define        return_header_corrupt(error)    { \
   g_set_error (error, GDK_PIXBUF_ERROR, \
-              GDK_PIXBUF_ERROR_HEADER_CORRUPT, _("Image header corrupt")); \
+              GDK_PIXBUF_ERROR_CORRUPT_IMAGE, _("Image header corrupt")); \
   return FALSE; \
 }
 #define        return_invalid_format(error)    { \
   g_set_error (error, GDK_PIXBUF_ERROR, \
-              GDK_PIXBUF_ERROR_UNKNOWN_FORMAT, _("Image format unknown")); \
+              GDK_PIXBUF_ERROR_UNKNOWN_TYPE, _("Image format unknown")); \
   return FALSE; \
 }
 #define        return_pixel_corrupt(error)     { \
   g_set_error (error, GDK_PIXBUF_ERROR, \
-              GDK_PIXBUF_ERROR_PIXEL_CORRUPT, _("Image pixel data corrupt")); \
+              GDK_PIXBUF_ERROR_CORRUPT_IMAGE, _("Image pixel data corrupt")); \
   return FALSE; \
 }
 
@@ -169,12 +169,11 @@ gdk_pixdata_serialize (const GdkPixdata *pixdata,
  * #GdkPixdata fields in network byte order, plus the pixel_data
  * bytes the structure points to.
  * The pixdata contents are reconstructed byte by byte and are checked
- * for validity, due to the checks, this function may prematurely abort
- * with errors, such as #GDK_PIXBUF_ERROR_HEADER_CORRUPT,
- * #GDK_PIXBUF_ERROR_PIXEL_CORRUPT or #GDK_PIXBUF_ERROR_UNKNOWN_FORMAT.
+ * for validity. This function may fail with %GDK_PIXBUF_CORRUPT_IMAGE
+ * or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE
  *
- * Return value: Upon successfull deserialization #TRUE is returned,
- * #FALSE otherwise
+ * Return value: Upon successfull deserialization %TRUE is returned,
+ * %FALSE otherwise
  **/
 gboolean
 gdk_pixdata_deserialize (GdkPixdata   *pixdata,
@@ -429,7 +428,7 @@ gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata,
        {
          g_free (data);
          g_set_error (error, GDK_PIXBUF_ERROR,
-                      GDK_PIXBUF_ERROR_PIXEL_CORRUPT,
+                      GDK_PIXBUF_ERROR_CORRUPT_IMAGE,
                       _("Image pixel data corrupt"));
          return NULL;
        }
@@ -779,23 +778,30 @@ gdk_pixdata_to_csource (GdkPixdata        *pixdata,
 }
 
 /**
- * gdk_pixbuf_new_from_stream:
- * @stream_length: Length in bytes of the @stream argument
- * @stream: Byte stream containing a serialized GdkPixdata structure
- * @copy_pixels: Whether to copy the pixels data, or keep direct pointers into the
- *               stream data for the resulting pixbuf
- * @error: GError return location, may be NULL to ignore errors
+ * gdk_pixbuf_new_from_inline:
+ * @data_length: Length in bytes of the @data argument
+ * @data: Byte data containing a serialized GdkPixdata structure
+ * @copy_pixels: Whether to copy the pixel data, or use direct pointers
+ *               @data for the resulting pixbuf
+ * @error: GError return location, may be %NULL to ignore errors
+ *
+ * Create a #GdkPixbuf from a flat representation that is suitable for
+ * storing as inline data in a program. This is useful if you want to
+ * ship a program with images, but don't want to depend on any
+ * external files.
  *
- * Create a #GdkPixbuf from a serialized GdkPixdata structure.
  * Gtk+ ships with a program called gdk-pixbuf-csource which allowes
- * for conversion of #GdkPixbufs into various kinds of C sources.
- * This is useful if you want to ship a program with images, but
- * don't want to depend on any external files.
+ * for conversion of #GdkPixbufs into such a inline reprentation.
+ * In almost all cases, you should pass the --raw flag to
+ * gdk-pixbuf-csource. A sample invocation would be:
  *
- * Since the inline pixbuf is read-only static data, you
- * don't need to copy it unless you intend to write to it.
- * For deserialization of streams that are run length encoded, the
- * decoded data is always a copy of the input stream.
+ *  gdk-pixbuf-csource --raw --name=myimage_inline myimage.png
+ * 
+ * For the typical case where the inline pixbuf is read-only static data,
+ * you don't need to copy the pixel data unless you intend to write to
+ * it, so you can pass %FALSE for @copy_pixels.  (If you pass --rle to
+ * gdk-pixbuf-csource, a copy will be made even if @copy_pixels is
+ * %FALSE, so using this option is generally a bad idea.)
  *
  * If you create a pixbuf from const inline data compiled into your
  * program, it's probably safe to ignore errors, since things will
@@ -803,22 +809,22 @@ gdk_pixdata_to_csource (GdkPixdata        *pixdata,
  * memory. For untrusted inline data located at runtime, you could
  * have corrupt inline data in addition.
  *
- * Return value: A newly-created #GdkPixbuf structure with a reference count of
- * 1, or NULL If error is set.
+ * Return value: A newly-created #GdkPixbuf structure with a reference,
+ *   count of 1, or %NULL if error is set.
  **/
 GdkPixbuf*
-gdk_pixbuf_new_from_stream (gint          stream_length,
-                           const guint8 *stream,
+gdk_pixbuf_new_from_inline (gint          data_length,
+                           const guint8 *data,
                            gboolean      copy_pixels,
                            GError      **error)
 {
   GdkPixdata pixdata;
 
-  if (stream_length != -1)
-    g_return_val_if_fail (stream_length > GDK_PIXDATA_HEADER_LENGTH, NULL);
-  g_return_val_if_fail (stream != NULL, NULL);
+  if (data_length != -1)
+    g_return_val_if_fail (data_length > GDK_PIXDATA_HEADER_LENGTH, NULL);
+  g_return_val_if_fail (data != NULL, NULL);
 
-  if (!gdk_pixdata_deserialize (&pixdata, stream_length, stream, error))
+  if (!gdk_pixdata_deserialize (&pixdata, data_length, data, error))
     return NULL;
 
   return gdk_pixbuf_from_pixdata (&pixdata, copy_pixels, error);